package com.zenithmind.exam.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.exam.pojo.entity.ExamParticipant;

import java.util.List;

/**
 * 考试参与者服务接口
 * 
 * @author ZenithMind
 * @since 2024-07-01
 */
public interface ExamParticipantService extends IService<ExamParticipant> {

    /**
     * 添加考试参与者
     * 
     * @param examId 考试ID
     * @param userId 用户ID
     * @param userName 用户姓名
     * @return 添加结果
     */
    boolean addParticipant(String examId, String userId, String userName);

    /**
     * 批量添加考试参与者
     * 
     * @param examId 考试ID
     * @param userIds 用户ID列表
     * @return 添加结果
     */
    boolean batchAddParticipants(String examId, List<String> userIds);

    /**
     * 移除考试参与者
     * 
     * @param examId 考试ID
     * @param userId 用户ID
     * @return 移除结果
     */
    boolean removeParticipant(String examId, String userId);

    /**
     * 批量移除考试参与者
     * 
     * @param examId 考试ID
     * @param userIds 用户ID列表
     * @return 移除结果
     */
    boolean batchRemoveParticipants(String examId, List<String> userIds);

    /**
     * 更新参与者状态
     * 
     * @param examId 考试ID
     * @param userId 用户ID
     * @param status 状态
     * @return 更新结果
     */
    boolean updateParticipantStatus(String examId, String userId, Integer status);

    /**
     * 根据考试ID获取参与者列表
     * 
     * @param examId 考试ID
     * @return 参与者列表
     */
    List<ExamParticipant> getParticipantsByExamId(String examId);

    /**
     * 根据用户ID获取参与的考试列表
     * 
     * @param userId 用户ID
     * @return 参与的考试列表
     */
    List<ExamParticipant> getParticipantsByUserId(String userId);

    /**
     * 分页查询考试参与者
     * 
     * @param page 分页参数
     * @param examId 考试ID
     * @param userName 用户姓名
     * @param status 状态
     * @return 分页结果
     */
    IPage<ExamParticipant> getParticipantPage(Page<ExamParticipant> page, String examId, 
                                             String userName, Integer status);

    /**
     * 检查用户是否可以参与考试
     *
     * @param examId 考试ID
     * @param userId 用户ID
     * @return 是否可以参与
     */
    boolean canUserParticipate(String examId, String userId);

    /**
     * 检查用户是否在参与者列表中
     *
     * @param examId 考试ID
     * @param userId 用户ID
     * @return 是否在参与者列表中
     */
    boolean isUserParticipant(String examId, String userId);

    /**
     * 统计考试参与人数
     * 
     * @param examId 考试ID
     * @param status 状态
     * @return 参与人数
     */
    Integer countParticipants(String examId, Integer status);

    /**
     * 获取考试的所有参与者用户ID
     * 
     * @param examId 考试ID
     * @return 用户ID列表
     */
    List<String> getParticipantUserIds(String examId);

    /**
     * 清空考试参与者
     * 
     * @param examId 考试ID
     * @return 清空结果
     */
    boolean clearParticipants(String examId);

    /**
     * 从Excel导入参与者
     * 
     * @param examId 考试ID
     * @param filePath 文件路径
     * @return 导入结果
     */
    boolean importParticipantsFromExcel(String examId, String filePath);

    /**
     * 导出参与者到Excel
     * 
     * @param examId 考试ID
     * @return 文件路径
     */
    String exportParticipantsToExcel(String examId);

    /**
     * 邀请用户参加考试
     * 
     * @param examId 考试ID
     * @param userIds 用户ID列表
     * @param message 邀请消息
     * @return 邀请结果
     */
    boolean inviteUsers(String examId, List<String> userIds, String message);

    /**
     * 用户加入考试
     * 
     * @param examId 考试ID
     * @param userId 用户ID
     * @return 加入结果
     */
    boolean joinExam(String examId, String userId);
}
